.\" Copyright (c) 2006-2020 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 28, 2006
.Dt AG_PANE 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Pane
.Nd agar paned container widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" IMAGE(http://libagar.org/widgets/AG_Pane.png, "A horizontal pane with a vertical sub-pane on the left")
The
.Nm
container divides its allocated space into two partitions (general-purpose
.Xr AG_Box 3
containers) horizontally or vertically.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_Pane *"
.Fn AG_PaneNewHoriz "AG_Widget *parent" "Uint flags"
.Pp
.Ft "AG_Pane *"
.Fn AG_PaneNewVert "AG_Widget *parent" "Uint flags"
.Pp
.Ft "void"
.Fn AG_PaneAttachBox "AG_Pane *pane" "int which" "AG_Box *box"
.Pp
.Ft "void"
.Fn AG_PaneAttachBoxes "AG_Pane *pane" "AG_Box *box1" "AG_Box *box2"
.Pp
.Ft "void"
.Fn AG_PaneSetDividerWidth "AG_Pane *pane" "int pixels"
.Pp
.Ft "void"
.Fn AG_PaneSetDivisionMin "AG_Pane *pane" "int which" "int min_w" "int min_h"
.Pp
.Ft "int"
.Fn AG_PaneMoveDivider "AG_Pane *pane" "int x"
.Pp
.Ft "int"
.Fn AG_PaneMoveDividerPct "AG_Pane *pane" "int pct"
.Pp
.Ft "void"
.Fn AG_PaneResizeAction "AG_Pane *pane" "enum ag_pane_resize_action resizeAction"
.Pp
.nr nS 0
The
.Fn AG_PaneNewHoriz
and
.Fn AG_PaneNewVert
functions allocate, initialize, and attach a new
.Nm
container, dividing space in the specified orientation.
.Pp
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_PANE_UNMOVABLE "
.It AG_PANE_DIV1FILL
By default, the size of the first (left or top) division is computed from its
child widgets, and the second division is sized to use the remaining space.
This option arranges for the first division to be sized from the remaining
space instead.
.It AG_PANE_FRAME
Render decorative frames.
.It AG_PANE_UNMOVABLE
Do not allow the user to move the divider.
.It AG_PANE_HFILL
Expand horizontally in parent container.
.It AG_PANE_VFILL
Expand vertically in parent container.
.It AG_PANE_EXPAND
Shorthand for
.Dv AG_PANE_HFILL | AG_PANE_VFILL .
.El
.Pp
If
.Dv AG_PANE_FRAME
is set, the depth of the frame can be adjusted by invoking
.Xr AG_BoxSetDepth 3
on the partitions.
.Pp
By default, the two
.Xr AG_Box 3
sub-containers of
.Nm
are created automatically.
.Fn AG_PaneAttachBox
allows existing boxes to be attached and re-used.
.Fa which
must be 0 or 1.
.Fn AG_PaneAttachBoxes
is a variant that accepts two box arguments.
.Pp
.Fn AG_PaneSetDividerWidth
sets the width of the divider widget in pixels.
If the argument is 0 then the divider will be invisible and not selectable.
If the argument is -1, reset to default (which is based on the zoom level).
.Pp
By default, the user is allowed to move the separator such that one of the
two partitions can be shrunk to zero.
.Fn AG_PaneSetDivisionMin
prevents this by setting a minimal geometry in pixels for the given partition
.Fa which
(which must be either 0 or 1).
If the value -1 is given, no minimum is set.
.Pp
The separator can also be moved programmatically with the
.Fn AG_PaneMoveDivider
function.
.Fn AG_PaneMoveDivider
tries to move the divider to the specified position
.Fa x
(in pixels) and returns the actual new position.
Note that
.Fn AG_PaneMoveDivider
will not have any effect if any of the
.Dv AG_PANE_FORCE_*
options are set.
.Pp
The
.Fn AG_PaneMoveDividerPct
variant accepts an argument in % of total available size.
If
.Fn AG_PaneResizeAction
is used with
.Dv AG_PANE_DIVIDE_PCT ,
this percentage is preserved through resizing.
.Pp
.Fn AG_PaneResizeAction
specifies the behavior of
.Nm
following a resize of the parent container widget.
Possible arguments include:
.Pp
.Bl -tag -compact -width  "AG_PANE_EXPAND_DIV1 "
.It AG_PANE_EXPAND_DIV1
Expand or shrink the left/upper division (default).
.It AG_PANE_EXPAND_DIV2
Expand or shrink the right/lower division.
.It AG_PANE_DIVIDE_EVEN
Divide the space evenly in two.
.It AG_PANE_DIVIDE_PCT
Divide the space by the percentage value specified in
.Fn AG_PaneMoveDividerPct .
.El
.Sh EVENTS
The
.Nm
widget does not generate any event.
.Sh STRUCTURE DATA
For the
.Ft AG_Pane
object:
.Bl -tag -width "AG_Box *div[2] "
.It Ft AG_Box *div[2]
Division containers (assuming that
.Fn AG_PaneAttachBox
was not used).
.It Ft int dmoving
Divider is currently being moved by the user (read-only).
.It Ft int dx
Actual divider position (read-only)
.El
.Sh EXAMPLES
The following code fragment displays two expanded, multi-line
.Xr AG_Textbox 3
widgets, separated horizontally by a
.Nm .
.Bd -literal -offset indent
AG_Window *win;
AG_Pane *pane;
AG_Textbox *textbox[2];

win = AG_WindowNew(0);
pane = AG_PaneNewVert(win, AG_PANE_EXPAND);
textbox[0] = AG_TextboxNew(pane->div[0],
    AG_TEXTBOX_MULTILINE|AG_TEXTBOX_EXPAND,
    NULL);
textbox[1] = AG_TextboxNew(pane->div[1],
    AG_TEXTBOX_MULTILINE|AG_TEXTBOX_EXPAND,
    NULL);
AG_PaneMoveDividerPct(pane, 50);
AG_WindowShow(win);
.Ed
.Sh SEE ALSO
.Xr AG_Box 3 ,
.Xr AG_Intro 3 ,
.Xr AG_MPane 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.
